/*
 * Copyright 2012 Dirk Vranckaert
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package eu.vranckaert.utility.location;

import android.location.Location;

/**
 * Date: 16/10/12
 * Time: 19:00
 *
 * @author Dirk Vranckaert
 */
public interface LocationService {
    /**
     * Start the location retrieval process. The most accurate position (aka location) will be retrieved in the most
     * performing way. Meaning that first of all we get the last known position. This is the quickest way to get some
     * indication of where the user is/was. Then we start polling for a location-update on all providers that are
     * registered. Each time a location is found it's returned in the method
     * {@link LocationServiceImpl#locationUpdated(android.location.Location)} but only if the location retrieved is the
     * first location found or if the newly found location is newer/better than the previously found location.<br/>
     * If this method is called again while there are still some location updates going on (for example GPS has no fix
     * yet) then all updates will be cancelled (all listeners will be removed) and the entire procedure will start all
     * over again.
     */
    void getLocation();

    /**
     * This will stop all location updates that are going on by canceling all the registered listeners. It's some kind
     * of reset of the {@link LocationServiceImpl} class because also the {@link LocationServiceImpl#bestLocationFound}
     * parameter is being reset.<br/>
     * This method should also be called from your {@link android.app.Activity}'s methods
     * {@link android.app.Activity#onPause()} and {@link android.app.Activity#onStop()}. If you want to restart the
     * location polling again on {@link android.app.Activity#onResume()} you can just call
     * {@link LocationServiceImpl#getLocation()}.
     */
    void stopLocationUpdates();

    /**
     * Checks if the service is currently busy retrieving location updates or not.
     * @return True if the service is currently searching for location updates, false if not.
     */
    boolean isBusy();

    /**
     * This method is called if a location is found from a certain provider. This method can be called multiple times as
     * information will be coming from multiple providers.
     * @param location The {@link android.location.Location} that is retrieved. This parameter will never be null!
     */
    abstract void locationUpdated(Location location);

    /**
     * This method is called when the timeout of {@link LocationServiceImpl#LOCATION_UPDATES_TIMEOUT} is reached so
     * notify you that the location will no longer be refreshed!
     * @param result {@link Boolean#TRUE} if in the entire process of determining a location found at least one
     *               location, {@link Boolean#FALSE} if in the entire process we could never determine a location (so
     *               not even for the last known location method).
     */
    abstract void done(boolean result);

    /**
     * Set the configuration parameter to retrieve the last known location before polling any of the location providers.
     * @param retrieveLastKnownLocationFirst True or false. Default is true. If set to true then
     * {@link eu.vranckaert.utility.location.LocationService#setStopIfOneLocationFound(boolean)} will always be set to false.
     */
    void setRetrieveLastKnownLocationFirst(boolean retrieveLastKnownLocationFirst);

    /**
     * Set the configuration parameter to stop searching for a location if one is found.
     * @param stopIfOneLocationFound True or false. Default is false. If set to true then
     * {@link eu.vranckaert.utility.location.LocationService#setRetrieveLastKnownLocationFirst(boolean)} will always be set to false.
     */
    void setStopIfOneLocationFound(boolean stopIfOneLocationFound);

    /**
     * Set the configuration parameter to retrieve the last known location before finishing the retrieval only if no
     * location has been found before. It's the final fallback method (but less accurate!). Default is false;
     * @param useLastKnownLocationFallback True or false.
     */
    void setUseLastKnownLocationFallback(boolean useLastKnownLocationFallback);
}
